On Hoffman2, to use apptainer, all you need to do is load the module

module load apptainer

• 🎉 Only module you need to load!
• No need to load tons of modules to run a single application
• 🌐 Expect MPI module if running parallel
  • module load intel/2022.1.1

apptainer pull [options]
apptainer pull docker://ubuntu:22.04

apptainer build [options]
apptainer build myapp.sif myapp.def

apptainer exec [options]
apptainer exec myapp.sif MYCOMMAND

apptainer run [options]
apptainer run myapp.sif "SCRIPT ARGRMENTS"

• Typically, you will build a container is by using an existing container as a base.

apptainer build myubuntu.sif docker://ubuntu:22.04

• This will create a new container file, myubuntu.sif, using the official Ubuntu 22.04 image from DockerHub.
• Note: SIF containers are immutable
  • Once built, they cannot be modified.
• You can run your apptainer commands from this new container.

apptainer shell myubuntu.sif
apptainer exec myubuntu.sif echo "Hi"

If you need a container that allows modifications, use the sandbox feature.

• Sandbox directories
  • Create a container within a writable directory (Sandbox)
  • Great to expermint installing software

sudo apptainer build --sandbox myubuntu-SB docker://ubuntu:22.04

• This create a directory myubuntu-SB that has the contents of the ubuntu image from DockerHub.
• Note the use of sudo
  • To ensure proper file permissions it is recommended to run this as an admin

• You can enter the sandbox container and modify it
  • Use --writable flag

sudo apptainer shell --writable myubuntu-SB

• Any modifications inside the sandbox persist after you exit.

Once you’re satisfied with the changes, convert it to a SIF container:

sudo apptainer build myNewUbuntu.sif myubuntu-SB

This packages the modified sandbox into a read-only .sif container called myNewUbuntu.sif.

A definition file provides precise instructions on how to build and configure a container.

apptainer build myapp.sif myapp.def

• Building from Apptainer definition files
  • Build a container from a definition file that has detailed information on how to install software inside the container
  • apptainer build myapp.sif myapp.def
    • myapp.sif is the new container built
    • myapp.def is the definition file

This definition file details how the new container would be build

Bootstrap: docker
From: docker.io/ubuntu:22.04

%labels
Example from apptainer.org

%post
    apt-get -y update
    apt-get -y install cowsay lolcat

%environment
    export LC_ALL=C
    export PATH=/usr/games:$PATH

%runscript
    date | cowsay | lolcat

In this example, we start with the Ubuntu 22.04 as a base OS. Then run commands from %post to create the final container.

• Build the container

apptainer build lolcow.sif lolcow.def

• Execute a command inside the container

apptainer exec lolcow.sif cowsay "Hello from Apptainer!"

• Run the container’s default script

apptainer run lolcow.sif

This will execute the runscript section (which prints a date-stamped ASCII cow 🐄 message in rainbow colors 🌈).

Once you create a SIF file, this is the container that you can transfer to Hoffman2 to run or share with others.

• This example uses PyTorch 🧠

• Similar to last week’s example

  • Though, instead of using PyTorch’s pre-build container, we will create our own container

• Create a container from a base source image
  • DockerHub has great minimal base containers
    • Ubuntu
    • Rocky Linux
    • CentOS
• Lets create a container based on Ubuntu 22.04

apptainer build --sandbox ubuntu_22.04_SB/ docker://ubuntu:22.04

This will create a Sandbox container ubuntu_22.04_SB

Next, we will start a WRITABLE interactive shell session in the sandbox image:

sudo apptainer shell --writable ubuntu_22.04_SB/

• --writable will allow us to modify the container

From here, we can run any commands we need to install PyTorch:

apt update
apt install -y python3 python3-pip
pip3 install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cpu
exit

Convert the sandbox container to a SIF file, pytorch.sif

sudo apptainer build pytorch.sif ubuntu_22.04_SB/

Test our new SIF container:

apptainer exec pytorch.sif python3 pytorch-code.py

We do not need to be root since we are just running python3.

Transfer our container:

scp pytorch.sif USERNAME@hoffman2.idre.ucla.edu:

Example job script to run on Hoffman2:

qsub pytorch.job

In this example, we will create a container with a chemistry application that I created in Grad School. This code will calcuate the engery of a molecule.

We will build this container by:

• Apptainter definition file (.def)
• Using Docker/Podman (Dockerfile)

• Definition Files are like the blueprint to building a custom container.
• Instead of interactively modifying a sandbox image, we can build a container with this Definition file
• The quill.def file has all steps needed to build the QUILL container.

Bootstrap: docker
From: ubuntu:20.04

%labels
Author Charles Peterson <cpeterson@oarc.ucla.edu>

%post
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
   git python3 python3-dev python3-pip \
   libeigen3-dev ca-certificates cmake make gcc g++
rm -rf /var/lib/apt/lists/*

pip3 install pyscf
ln -s /usr/bin/python3 /usr/bin/python
mkdir -pv /apps
cd /apps
git clone https://github.com/charliecpeterson/QUILL
cd QUILL
mkdir build ; cd build
cmake ..
make

%environment
export PATH=/apps/QUILL/build:$PATH

• Docker or Podman can be use to create containers
  • Then convert Docker/Podman container to SIF format
• I will be using Podman
  • Docker and Podman have same syntax
  • Replace podman with docker

docker build
docker images
docker pull
docker run

podman build
podman images
podman pull
podman run

• Dockerfile-quill file is used by Docker to create container

FROM ubuntu:20.04

## Author Charles Peterson <cpeterson@arc.ucla.edu>

RUN apt-get update \
     && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
   git python3 python3-dev python3-pip \
   libeigen3-dev ca-certificates cmake make gcc g++ \
   && rm -rf /var/lib/apt/lists/*

RUN pip3 install pyscf ; ln -s /usr/bin/python3 /usr/bin/python

RUN mkdir -pv /apps \
    && cd /apps \
    && git clone https://github.com/charliecpeterson/QUILL \
    && cd QUILL \
    && mkdir build ; cd build \
    && cmake .. ; make

ENV PATH=/apps/QUILL/build:$PATH

Create Docker container

podman build . -t quill:1.0 -f Dockerfile-quill

podman image list

podman save quill:1.0 > quill.tar

apptainer build quill.sif docker-archive://quill.tar

scp quill.sif USERNAME@hoffman2.idre.ucla.edu:

• Lets create a repo on GitHub
  • Look for the Packages tab
• Same syntax as before
  • registry location is ghcr.io

podman tag quill:1.0 ghcr.io/charliecpeterson/quill:1.0
podman push ghcr.io/charliecpeterson/quill:1.0

apptainer pull docker://ghcr.io/charliecpeterson/quill:1.0

DockerHub and GitHub Packages are popular cloud registries. You can create and deploy a local container registry.

• https://docs.docker.com/registry/deploying/

Once the container is on Hoffman2, submit job.

#!/bin/bash
#$ -cwd
#$ -o quill.$JOB_ID
#$ -j y
#$ -l h_rt=1:00:00,h_data=15G
#$ -pe shared 1
#$ -l arch=intel-gold*

# load the job environment:
. /u/local/Modules/default/init/modules.sh
module load apptainer

# Container part: apptainer exec QUILL.sif
# Command: QUILL.x /apps/QUILL/input.inp
apptainer exec quill.sif QUILL.x test.inp

qsub test.job

In this example, we will use MiniForge to install h2o packages inside python and R.

• The h2o.def file
  • Use of %runscript to setup MiniForge env for apptainer run
    • the $@ take arguments as a string from the command line

Bootstrap: docker
From: ubuntu:22.04

%labels
Author Charles Peterson <cpeterson@oarc.ucla.edu>

%post
export DEBIAN_FRONTEND=noninteractive
apt -y update ; apt -y upgrade
apt install -y  wget libbz2-dev wget git gcc  libreadline-dev zlib1g-dev default-jre default-jdk

#Install Miniforge
cd /tmp
wget https://github.com/conda-forge/miniforge/releases/download/24.11.3-0/Miniforge3-24.11.3-0-Linux-x86_64.sh
bash Miniforge3-24.11.3-0-Linux-x86_64.sh -b -p /opt/miniforge
bash -c "source /opt/miniforge/etc/profile.d/conda.sh
conda create -n h2oai h2o -c h2oai -c conda-forge
"

%runscript
exec bash -c "source /opt/miniforge/etc/profile.d/conda.sh
conda activate h2oai
$@"

In the runscript, it will activate the conda environment, h2oai, and run the command that follows the apptainer run h2o.sif command

• Create a container with Jupyter
  • Useful so you can run same Jupyter setup anywhere
  • Install all packages you need in container

• jupyter.def
  • Apptainer Def file
  • Starts with a pre-built python 3.8.13 container
  • Adds jupyter, pandas, and seaborn

apptainer build jupyter.sif jupyter.def 
scp jupyter.sif hoffman2.idre.ucla.edu: